package org.jplcc;

import java.util.Date;

/**
 * <P>
 * A connection (session) with a specific PLC. Reading and writing data are
 * executed within the context of a connection.
 * <P>
 * A <code>Connection</code> object's PLC is able to provide information
 * describing its supported java type, the capabilities of this connection, and
 * so on. This information is obtained with the <code>getMetaData</code> method.
 * 
 * @see DriverManager#getConnection
 */

public interface Connection {

	/**
	 * Releases this <code>Connection</code> object's database and JPLCC
	 * resources immediately instead of waiting for them to be automatically
	 * released.
	 * <P>
	 * Calling the method <code>close</code> on a <code>Connection</code> object
	 * that is already closed is a no-op.
	 * <P>
	 * 
	 * @exception JPLCCException
	 *                if a plc access error occurs
	 */
	void close() throws JPLCCException;

	/**
	 * Retrieves whether this <code>Connection</code> object has been closed. A
	 * connection is closed if the method <code>close</code> has been called on
	 * it or if certain fatal errors have occurred. This method is guaranteed to
	 * return <code>true</code> only when it is called after the method
	 * <code>Connection.close</code> has been called.
	 * <P>
	 * This method generally cannot be called to determine whether a connection
	 * to a PLC is valid or invalid. A typical client can determine that a
	 * connection is invalid by catching any exceptions that might be thrown
	 * when an operation is attempted.
	 * 
	 * @return <code>true</code> if this <code>Connection</code> object is
	 *         closed; <code>false</code> if it is still open
	 * @exception JPLCCException
	 *                if a plc access error occurs
	 */
	boolean isClosed() throws JPLCCException;

	/**
	 * Retrieves a <code>PLCMetaData</code> object that contains metadata about
	 * the PLC to which this <code>Connection</code> object represents a
	 * connection. The metadata includes information about the plc's supported
	 * data type, the capabilities of this connection, and so on.
	 * 
	 * @return a <code>PLCMetaData</code> object for this
	 *         <code>Connection</code> object
	 * @exception JPLCCException
	 *                if a plc access error occurs or this method is called on a
	 *                closed connection
	 */
	PLCMetadata getMetaData() throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.BOOL</code> in
	 * the JPLCC specification. The boolean represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	boolean readBool(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.BOOL_ARRAY</code> in the JPLCC specification. The booleans
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	boolean[] readBools(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.BYTE</code> in
	 * the JPLCC specification. The byte represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	byte readByte(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.BYTE_ARRAY</code> in the JPLCC specification. The bytes
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	byte[] readBytes(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.SHORT</code> in
	 * the JPLCC specification. The short represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	short readShort(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.SHORT_ARRAY</code> in the JPLCC specification. The shorts
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	short[] readShorts(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.INT</code> in
	 * the JPLCC specification. The int represent the raw values returned by the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	int readInteger(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.INT_ARRAY</code> in the JPLCC specification. The integers
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	int[] readIntegers(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.LONG</code> in
	 * the JPLCC specification. The long represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	long readLong(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.LONG_ARRAY</code> in the JPLCC specification. The longs
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	long[] readLongs(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.FLOAT</code> in
	 * the JPLCC specification. The float represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	float readFloat(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.FLOAT_ARRAY</code> in the JPLCC specification. The floats
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	float[] readFloats(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.DOUBLE</code>
	 * in the JPLCC specification. The double represent the raw values returned
	 * by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	double readDouble(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.DOUBLE_ARRAY</code> in the JPLCC specification. The doubles
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	double[] readDoubles(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.DATE</code> in
	 * the JPLCC specification. The Date represent the raw values returned by
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	Date readDate(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.DATE_ARRAY</code> in the JPLCC specification. The Dates
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	Date[] readDates(String tag, int length) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a <code>Type.STRING</code>
	 * in the JPLCC specification. The String represent the raw values returned
	 * by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	String readString(String tag) throws JPLCCException;

	/**
	 * Retrieves the value of the designated tag as a
	 * <code>Type.STRING_ARRAY</code> in the JPLCC specification. The Strings
	 * represent the raw values returned by the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param length
	 *            the number of array elements to be read.
	 * @return the tag value
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	String[] readStrings(String tag, int length) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.BOOL</code> in the
	 * JPLCC specification. The boolean represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeBool(String tag, boolean value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.BOOL_ARRAY</code>
	 * in the JPLCC specification. The booleans represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeBools(String tag, boolean[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.BYTE</code> in the
	 * JPLCC specification. The byte represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeByte(String tag, byte value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.BYTE_ARRAY</code>
	 * in the JPLCC specification. The bytes represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeBytes(String tag, byte[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.SHORT</code> in the
	 * JPLCC specification. The short represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeShort(String tag, short value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.SHORT_ARRAY</code>
	 * in the JPLCC specification. The shorts represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeShorts(String tag, short[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.INT</code> in the
	 * JPLCC specification. The int represent the raw values sent to the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeInteger(String tag, int value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.INT_ARRAY</code> in
	 * the JPLCC specification. The integers represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeIntegers(String tag, int[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.LONG</code> in the
	 * JPLCC specification. The long represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeLong(String tag, long value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.LONG_ARRAY</code>
	 * in the JPLCC specification. The longs represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeLongs(String tag, long[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.FLOAT</code> in the
	 * JPLCC specification. The float represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeFloat(String tag, float value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.FLOAT_ARRAY</code>
	 * in the JPLCC specification. The floats represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeFloats(String tag, float[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.DOUBLE</code> in
	 * the JPLCC specification. The double represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeDouble(String tag, double value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.DOUBLE_ARRAY</code>
	 * in the JPLCC specification. The doubles represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeDoubles(String tag, double[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.DATE</code> in the
	 * JPLCC specification. The Date represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeDate(String tag, Date value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.DATE_ARRAY</code>
	 * in the JPLCC specification. The Dates represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeDates(String tag, Date[] value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.STRING</code> in
	 * the JPLCC specification. The String represent the raw values sent to the
	 * driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeString(String tag, String value) throws JPLCCException;

	/**
	 * Write the value to the designated tag as a <code>Type.STRING_ARRAY</code>
	 * in the JPLCC specification. The Strings represent the raw values sent to
	 * the driver.
	 * 
	 * @param tag
	 *            the name of the tag.
	 * @param value
	 *            the value sent to the driver.
	 * @exception JPLCCException
	 *                if the tag is not valid; if a PLC access error occurs or
	 *                this method is called on a closed connection
	 */
	void writeStrings(String tag, String[] value) throws JPLCCException;
}
